Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Writing Scriptable Parts
Introduction
Writing Apple event event handlers and object accessors for the Apple event object model is a little different for OpenDoc developers. There are a some new protocols and things to be aware of as you code. Fortunately, most of what you already know about writing event handlers and object accessors for OSA compliant languages is still true. Changes have been kept to a minimum.
This document assumes familiarity with the Inside Macintosh-Collaborative Computing volume and OpenDoc.
General
OpenDoc implements some of the Apple event and Object Support Library calls itself. You must use the corresponding routines defined in OpenDoc instead of directly calling the Apple event or Object Support Library routines. Routines for which there is no corresponding OpenDoc function may be called directly. Apple event cover routines are contained in the class ODMessageInterface. Object Support Library cover routines are contained in the class ODNameResolver. The class SIHelper contains routines corresponding to those found in both Apple events and the Object Support Library.
When this document refers to parts, this will apply to both parts and the document shell application. The shell is a special part to the Semantic Events system whose corresponding ODPart* is equal to the constant kODAppShell.
OpenDoc reserves the DescType 'swch' for use in tokens. Developers may not use this value in the descriptorType field of their tokens.
ODBaseSemanticInterface, ODSemanticInterface
ODBaseSemanticInterface is an extension class (subclass of ODExtension) that furnishes the API that parts must implement in order to support Apple events and/or scripting in their parts. Parts must create and instantiate a subclass of ODBaseSemanticInterface to do this. The part must also implement the part methods HasExtension and GetExtension, the latter returning an object which is a subclass of ODBaseSemanticInterface . The ODType constant for the ODSemanticInterface extension is “SemanticInterface”.
The ODSemanticInterface class is a subclass of ODBaseSemanticInterface that is provided with OpenDoc. The implementation of the ODSemanticInterface calls a C++ class in which the part can install event handlers, object accessors, etc.
There is one special ODSemanticInterface class available from the ODSession class. The document shell’s semantic interface is obtained through the ODSession::GetShellSemtInterface function. The document shell need not instantiate an ODSemanticInterface itself as one is always instantiated for it. To install system level callback functions, use the corresponding Apple event Manager and OSL routines specifying “true” for the isSystemHandler parameter.
SIHelper
ODSemanticInterface specifies an API for calling your event handlers and object accessors, but does not allow you to install callback functions for these. Instead, it calls a C++ helper class that can be used to store these callbacks. The interface to this C++ helper class, SIHelperAbs, is specified in the file SIHlpAbs.h. We provide a subclass of this class, SIHelper, that implements an interface that allows registering of callbacks and object accessors very much like the routines of the Apple event Manager and the OSL. Part developers are free to implement their own subclass of SIHelperAbs, just as they are free to implement their own subclass of ODBaseSemanticInterface.
The callback routines that you register here contain an extra ODPart* parameter. This is to allow you to access your part object from the callback routine. You can share instances of SIHelper classes between instances of ODSemanticInterfaces. Since there can be only one part per ODSemanticInterface, ODSemanticInterface will furnish the correct ODPart* to the SIHelper class. For the document shell, this parameter will always be equal to the constant kODAppShell. If parts are sharing instances of SIHelper classes, they should not put a reference to themselves in the refCon parameter of the callback. The one exception is the document shell which will probably want to use the refcon to pass some meaningful pointer around to allow it access to its storage from inside its event handlers and object accessors.
Apple events
OpenDoc does its own dispatching of Apple events. This is to allow the event to be directed to the right part, and to enable OpenDoc to direct replies back to the part that sent the original event. However, the behavior is almost exactly the same as in Apple events. The only difference is that the developer no longer has access to the returnID parameter to the Apple event. This is now for OpenDoc’s internal use only.
Apple event Object Model
OpenDoc uses a new OSL which has the ability to deal with different “contexts” within one process. These contexts could be plug-in tools, different “modes” of the application, or, in the case of OpenDoc, different parts. OpenDoc uses this OSL to allow access to parts and to allow each part to have its own set of object accessor routines and event handlers. Currently this OSL is part of OpenDoc and OpenDoc parts must use it.
The document shell application should implement accessors for all OpenDoc objects, most notably windows and documents and drafts. Note that when talking about a document, the user will often be talking about the root part of the latest draft of the document. The document shell should be intelligent and provide default access to the root part and the current draft from the NULL context. Additionally, the document shell should implement accessors for getting parts from various container types and for getting parts from a part container and for getting the properties of parts. The reason for this is elucidated below in the subsection titled The Spcial Token in the section titled Protocols.
Parts should implement object accessor routines as if the part were a standalone applications The part itself is the NULL container. If a part allows embedding, it should additionally implement accessors for getting parts from various containers, for getting the properties of parts and for getting a part from a part container. The reason for this is elucidated below in the section titled Protocols.
Resolve has a new parameter, an ODPart*, to specify the context part from which to start a resolution. It has lost its callbackFlags parameter since the callback flags must be specified on a part-by-part basis through the routine ODSemanticInterface::SetOSLSupportFlags.
Apple event Registry
OpenDoc adds another noun to the Apple event registry, “part”, code = ‘part’. To the scripter, a “part” in this sense really represents a frame, and not a part in the technical sense at all. Another new noun that OpenDoc adds to the registries in “draft”. The code for draft has not yet been determined.
Addressing
To address an OpenDoc part, an object specifier must be used as the direct parameter of the Apple event. Applications sending events to an OpenDoc document will construct the appropriate object specifier themselves. Parts sending events to other parts must use the routine CreatePartObjSpec to address another part or create an object specifier themselves that represents the destination part. Additionally, CreatePartAddrDesc must be used to create an address descriptor that identifies the process in which the destination part lives.
Sequence of Event Processing
OpenDoc reverses the typical sequence of event processing. The object specifier in the direct parameter of an Apple event is resolved before any event handler is called since the direct object may contain a description of the destination part. The token returned from the resolution replaces the object specifier in the direct parameter of the Apple event before a part’s event handler is called.
Protocols
Tokens in general
<Parts no longer need to call CreateToken and the first four bytes of the dataHandler of a token are no longer reserved by OpenDoc.>
The Special Token
When an object accessor routine is asked to access an object or an unknown property from a container of descriptorType cPart, the accessor must pass back a special token to signal to OpenDoc its failure to furnish the required token. This is done by calling ODNameResolver::CreateSwapToken to initialize the token, passing in the ODFrame* that is the current visual context for resolution. The accessor then need take no further action and should simply return. OpenDoc will notice the special token type and will “retry” the object access in the context of the given part.
Coercion Handlers
Any coercion handlers installed by parts or the document shell are only called if and when that part or the document shell is the “current context”. Normally, the document shell is the current context. There are two situations in which a part can become the current context. The first happens during the resolution of an object specifier. If the object accessor of a part must be called during a resolution, that part then becomes the current context. When a part’s event handler is called, that part becomes the current context as well. Coercion handlers are not chained by OpenDoc. An embedded part does not inherit the coercion handlers of its embedding part and a part does not inherit the coercion handlers of the shell.
Unsupported features of Apple events and the OSL
•Calling ODSemanticInterface::RemoveSpecialHandler with the keyword keySelectProc will not disable the OSL functionality.
•The key keySelectProc cannot be passed to ODSemanticInterface::InstallSpecialHandler as it can in the Apple event Manager. An exception will be thrown.
